{
	"info": {
		"_postman_id": "c1aac76f-afed-42f0-b227-ad3cb8c90e01",
		"name": "Docmosis Cloud (DWS4) - API",
		"description": "# Introduction\n\n## Overview\n\nDocmosis Cloud Service provides an easy way to generate dynamic documents from virtually any application.\n\nThis cutdown Postman collection contains a subset of the available Docmosis Cloud API endpoints.\n\n### Related Reading\n\nRead more about [<i>features of the Docmosis Cloud</i>](https://www.docmosis.com/products/cloud/).\n\nView the full [<i>Cloud API Documentation.</i>](https://resources.docmosis.com/documentation/cloud/dws4)\n\n## Key Concepts\n\n### HTTP Methods\n\nAll requests to the Cloud API should be made using the HTTPS POST method.\n\n### Content-Type\n\nThe content-type varies depending on the service being used. All services accept `multi-part/form-data`.\n\nThe /render service is the most versatile and can also accept `application/json`, `application/xml` and `application/x-www-form-urlencoded`.\n\n### Parameters\n\nRequests must include the API access key in either the header or body parameters. All other parameters should be body parameters. The API does not use query string parameters.\n\n### Character Encoding\n\nAll data passed to the Cloud API should be UTF-8 encoded. If data is passed containing special characters, it must be UTF-8 encoded, otherwise unexpected characters may appear in resulting documents.\n\n### Fonts in Templates\n\nTemplates should only use fonts that are available on the Cloud Service. If fonts are used which are not installed, unexpected font substitutions may occur in PDF documents or inaccurate page references when using indexes or tables of content.\n\nPlease see [<i>DWS4 Font List</i>](https://resources.docmosis.com/content/faq/is-there-a-list-of-fonts-for-docmosis-cloud-dws4) for a list of available fonts.\n\n### Production vs Development Mode\n\nSome API endpoints provide the option to operate in a forgiving manner (development mode) or in a very strict manner (production mode).\n\nThe intention is that, in development mode, requests to the endpoints will succeed even if errors are detected, helping users to locate the error and make the necessary adjustments.\n\nIn production mode, requests will fail with diagnostic information returned in the response to the calling application.\n\n# The Service API\n\n## Endpoint URLs and Processing Locations\n\nWhen calling the API the Base URL determines the location that will process the request.\n\nThe available locations are:\n\n| **Location** | **Base URL** |\n| --- | --- |\n| United States | [https://us1.dws4.docmosis.com/api/](https://us1.dws4.docmosis.com/api/) |\n| Europe | [https://eu1.dws4.docmosis.com/api/](https://eu1.dws4.docmosis.com/api/) |\n| Australia | [https://au1.dws4.docmosis.com/api/](https://au1.dws4.docmosis.com/api/) |\n\nEach processing location is independent of the others and each Cloud Account has access to all locations.\n\nEach location has its own templates and all processing is confined to that location to support data-sovereignty and privacy requirements as well as optimizing performance.\n\nFor example, to upload a template to the Cloud Service in the US and then render it, these two API URLs would be used:\n\nhttps://**us1**.dws4.docmosis.com/api/**uploadTemplate**\n\nhttps://**us1**.dws4.docmosis.com/api/**render**\n\nSince each Docmosis location is independent of the others the templates must be stored in the same location as the location being used for rendering.\n\n## Response Codes and Messages\n\nFor every request made to the Cloud API, the first action should be to check the response status code to determine whether the call succeeded or failed. The choice can then be made whether to check for further information in the response body.\n\nThe API returns status codes as follows:\n\n| **Status Code** | **Definition** |\n| --- | --- |\n| 200 | Successful operation |\n| 400 | The request is not valid or indicates a not-ready status. |\n| 500 | A server error has occurred |\n| 404 | Invalid URL (not found) |\n| 429 | Too many requests |\n\nOther 4** and 5** response codes may also occur. Applications should always confirm that they received a 200 response before assuming success and processing the result.\n\nThe Cloud Service also returns information about the result in JSON or XML as follows:\n\n| **Field** | **Value** |\n| --- | --- |\n| Succeeded | \"true\" or \"false\". |\n| shortMsg | A short message about the result. In the case of an error this will be a short error message. It may be blank in the case of a successful operation. |\n| longMsg | A more descriptive message about the result. In the case of an error this will be a long error message. It may be blank. |\n\nEach service may also return additional information in the response information, as indicated in the sections to follow.\n\nIn the case of some errors, the response body will NOT include the data structure containing \"succeeded\", \"shortMsg\" etc. This is because some errors indicate the call failed to even reach the Cloud Service. For example, a status code 404 indicates a bad URL in which case the status code alone is enough to indicate the nature of the problem.\n\n## Troubleshooting\n\nThere are many resources available on the [Docmosis Resources website](https://resources.docmosis.com) including FAQs, examples and tutorials that may help with troubleshooting problems.\n\n# Key Render Parameters\n\n## Sending Data\n\nThe “data” parameter should contain the data, that will be merged with the template, in JSON or XML format.\n\n## Sending Data as Parameters\n\nBy default, only the parameters listed below should be included when calling the /render service. This is known as “strict” mode and sending unknown parameters to the service will result in an error.\n\nThe parameter \"strictParams\" can be set to \"false\" to disable this behavior.\n\nIn this case unknown parameters will be treated as data and will be merged with the template.\n\n## Output Format\n\nThe format of the generated document will be determined by:\n\n• The parameter \"outputName\" and the file extension used in the file name. Eg “resume.pdf” will result in a PDF file being generated.\n\n• The parameter \"outputFormat\".\n\n\"outputFormat\" overrides any format implied by \"outputName\".\n\n## Dev/Prod Mode\n\nThe /render service works in production mode by default. Any errors that occur during the document generation process are considered fatal and the call will fail.\n\nThis may be overridden by setting the “devMode” parameter to “true”. In this case the service will do its best to generate a document and where possible errors will be highlighted in the generated document.\n\n## Sending Images\n\nInserting an image in to a document requires two things:\n\n• The template requires a “placeholder image”, that controls where the image will appear.\n\n• The data determines what image is to appear.\n\nPlease refer to the [sending image data FAQ](https://resources.docmosis.com/content/faq/how-to-send-image-data-or-retrieve-images-from-a-file-or-url) for more information.\n\n## Document Delivery\n\nThe “storeTo” parameter controls how the generated document will be delivered.\n\nIf no value is provided for “storeTo”, the default behavior is “stream”. In this case the document will be returned in the response to the calling application. The calling application can read the returned binary or base64 encoded stream to obtain the document.\n\nThe service can deliver the generated document: via email; to an AWS S3 bucket; or to several destinations at once, and optionally send different formats for delivery to each destination.\n\nAs a simple example try setting “storeTo” to: “mailto:[bob@example.com](https://mailto:bob@example.com)”. This indicates the generated document should be sent to the email address provided.\n\nContact Support:  \nEmail: [support@docmosis.com](https://mailto:support@docmosis.com)",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "34392741"
	},
	"item": [
		{
			"name": "Ping",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "{{baseUrl}}/ping",
					"host": [
						"{{baseUrl}}"
					],
					"path": [
						"ping"
					]
				},
				"description": "The ping service provides a direct check that the Docmosis Cloud services are online and there is at least one Docmosis server listening.  This is useful for diagnostics and for monitoring purposes.  The response is empty, and the http response code “200” is the success indicator."
			},
			"response": []
		},
		{
			"name": "Environment Ready",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"value": "multipart/form-data"
					},
					{
						"key": "Accept",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "formdata",
					"formdata": [
						{
							"key": "accessKey",
							"value": "string",
							"description": "(Required) The unique API key identifying the Environment.  This can be found in the API Keys area in the Cloud Console.",
							"type": "text"
						}
					]
				},
				"url": {
					"raw": "{{baseUrl}}/environment/ready",
					"host": [
						"{{baseUrl}}"
					],
					"path": [
						"environment",
						"ready"
					]
				},
				"description": "The Environment ready service provides the ability to check whether an environment is ready to service document requests.  This service is suitable for linking to automated monitoring systems for important Docmosis Environments.\nThis service confirms whether the Environment is active and within quota limits. Note: Environments may be over quota (ie. hard limit is not applied) and still operational, in which case this service will indicate the environment is ready, even though over quota.\nConsider creating an API Key in the Environment specifically for use with this service.\nresponse code: 200 means ready\nresponse code: 400 means not ready"
			},
			"response": []
		},
		{
			"name": "List Templates",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"value": "multipart/form-data"
					},
					{
						"key": "Accept",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "formdata",
					"formdata": [
						{
							"key": "accessKey",
							"value": "string",
							"description": "(Required) The unique API key identifying the Environment.  This can be found in the API Keys area in the Cloud Console.",
							"type": "text"
						}
					]
				},
				"url": {
					"raw": "{{baseUrl}}/listTemplates",
					"host": [
						"{{baseUrl}}"
					],
					"path": [
						"listTemplates"
					]
				},
				"description": "List templates lists the templates available."
			},
			"response": []
		},
		{
			"name": "Render",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"value": "multipart/form-data"
					},
					{
						"key": "Accept",
						"value": "application/octet-stream"
					}
				],
				"body": {
					"mode": "formdata",
					"formdata": [
						{
							"key": "accessKey",
							"value": "string",
							"description": "(Required) The unique API key identifying the Environment.  This can be found in the API Keys area in the Cloud Console.",
							"type": "text"
						},
						{
							"key": "outputName",
							"value": "output.pdf",
							"description": "(Required) The name to give the rendered document.  If no format is specified (see outputFormat), the format of the resulting document is derived from the extension of this name.  For example, \"resume1.pdf\" implies a PDF format document.    The name may be supplied without an extension (eg \"resume1\") and the outputFormat parameter will specify the format(s) to return.\n\nIf multiple template names are specified, multiple (matching) output names can be specified to create a zip of named outputs.",
							"type": "text"
						},
						{
							"key": "templateName",
							"value": "/samples/WelcomeTemplate.docx",
							"description": "(Required) The name of the template to use.  The template must have been uploaded previously with the template upload request or via the Cloud Console.\n\nMultiple templates can be specified using the ; character to separate the templates.  With multiple template names, a single outputName for PDF output results in a single combined PDF.  In all other cases, a ZIP file will be returned containing each rendered document.",
							"type": "text"
						},
						{
							"key": "data",
							"value": "[object Object]",
							"description": "The Data that will populate the document.  This may be either XML or JSON format.  The type of data given determines the format of the response.\n\n",
							"type": "text"
						},
						{
							"key": "devMode",
							"value": "string",
							"description": "The render service can be used in development or production modes respectively.  If set to \"y\", \"yes\" or \"true\" this operation will work in \"dev\" mode, meaning that if something is incorrect in the template, data or instructions, Docmosis will do its best to produce a document.  Such a document may contain errors such as missing images and data, and wherever possible, Docmosis will highlight problems to indicate the failure.  \n\nIn production mode, errors in document rendering will result in a failure result only, and no document will be produced.   The production mode is to ensure that a bad document is never produced/delivered to a recipient.   The default mode is production (that is, devMode is off).  Default = false.",
							"type": "text",
							"disabled": true
						},
						{
							"key": "storeTo",
							"value": "string",
							"description": "Specify where to send the resulting document.  If no specification is given, \"stream\" is assumed and the result will be streamed back to the requester, otherwise the ‘;’ semi-colon delimited list of destinations will receive the result.\n\nValid options are stream, mailto, s3.  Default = stream.",
							"type": "text",
							"disabled": true
						}
					]
				},
				"url": {
					"raw": "{{baseUrl}}/render",
					"host": [
						"{{baseUrl}}"
					],
					"path": [
						"render"
					]
				},
				"description": "The /render service is the document production ‘work-horse’, and it is expected to be the main service that all applications will use.\n\nSee notes above for more details on key parameters.\n"
			},
			"response": []
		}
	],
	"variable": [
		{
			"key": "baseUrl",
			"value": "https://us1.dws4.docmosis.com/api"
		}
	]
}